/*
 * // Bristleback plugin - Copyright (c) 2010 bristleback.googlecode.com
 * // ---------------------------------------------------------------------------
 * // This program is free software; you can redistribute it and/or modify it
 * // under the terms of the GNU Lesser General Public License as published by the
 * // Free Software Foundation; either version 3 of the License, or (at your
 * // option) any later version.
 * // This library is distributed in the hope that it will be useful,
 * // but without any warranty; without even the implied warranty of merchantability
 * // or fitness for a particular purpose.
 * // You should have received a copy of the GNU Lesser General Public License along
 * // with this program; if not, see <http://www.gnu.org/licenses/lgpl.html>.
 * // ---------------------------------------------------------------------------
 */

package pl.bristleback.server.bristle.binding.resolvers;

import org.jwebsocket.token.Token;
import pl.bristleback.server.bristle.binding.BindingResult;
import pl.bristleback.server.bristle.binding.NestedFieldInformation;

/**
 * Classes implementing this interface are responsible for binding token data into object,
 * using previously created binding information wrapper.
 * Binding engines should specify what kind of token they are able process,
 * because of token implementations incompatibility ({@link org.jwebsocket.token.JSONToken} and {@link org.jwebsocket.token.MapToken}).
 * Binding engine is set individually for every binding operation.
 * If it is not specified by user on {@link pl.bristleback.server.bristle.binding.Bind} annotation,
 * default binder implementation is provided. Default implementation of binding engine can be changed from
 * {@link pl.bristleback.server.bristle.binding.resolvers.DefaultBindingEngine} by setting correspondent property in jwebsocket.xml.
 *
 * @author Wojciech Niemiec
 * @see pl.bristleback.server.bristle.config.BristleConfigurationElement#DEFAULT_BINDING_ENGINE Bristleback configuration
 */
public interface BindingEngine {

  /**
   * Performs binding operation, processing fields from token into object of given type.
   * Fields and validation elements are wrapped into {@link pl.bristleback.server.bristle.binding.NestedFieldInformation} object.
   * Validation errors should be added to returning {@link pl.bristleback.server.bristle.binding.BindingResult} object.
   * Any other exception, like class cast exception, should be thrown as they are considered as programmer mistakes.
   *
   * @param object          object instance.
   * @param token           token with data.
   * @param beanInformation fields to bind and validation information wrapper.
   * @param <T>             type of returned object.
   * @return binding result wrapper, containing object and validation errors.
   */
  <T> BindingResult<T> bind(T object, Token token, NestedFieldInformation beanInformation);
}
